home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / lib / mozilla-firefox / idl / nsITransport.idl < prev    next >
Encoding:
Text File  |  2006-05-08  |  8.2 KB  |  193 lines
  1. /* ***** BEGIN LICENSE BLOCK *****
  2.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  3.  *
  4.  * The contents of this file are subject to the Mozilla Public License Version
  5.  * 1.1 (the "License"); you may not use this file except in compliance with
  6.  * the License. You may obtain a copy of the License at
  7.  * http://www.mozilla.org/MPL/
  8.  *
  9.  * Software distributed under the License is distributed on an "AS IS" basis,
  10.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11.  * for the specific language governing rights and limitations under the
  12.  * License.
  13.  *
  14.  * The Original Code is Mozilla.
  15.  *
  16.  * The Initial Developer of the Original Code is
  17.  * Netscape Communications Corporation.
  18.  * Portions created by the Initial Developer are Copyright (C) 2002
  19.  * the Initial Developer. All Rights Reserved.
  20.  *
  21.  * Contributor(s):
  22.  *   Darin Fisher <darin@netscape.com>
  23.  *
  24.  * Alternatively, the contents of this file may be used under the terms of
  25.  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26.  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27.  * in which case the provisions of the GPL or the LGPL are applicable instead
  28.  * of those above. If you wish to allow use of your version of this file only
  29.  * under the terms of either the GPL or the LGPL, and not to allow others to
  30.  * use your version of this file under the terms of the MPL, indicate your
  31.  * decision by deleting the provisions above and replace them with the notice
  32.  * and other provisions required by the GPL or the LGPL. If you do not delete
  33.  * the provisions above, a recipient may use your version of this file under
  34.  * the terms of any one of the MPL, the GPL or the LGPL.
  35.  *
  36.  * ***** END LICENSE BLOCK ***** */
  37.  
  38. #include "nsISupports.idl"
  39.  
  40. interface nsIInputStream;
  41. interface nsIOutputStream;
  42. interface nsITransportEventSink;
  43. interface nsIEventTarget;
  44.  
  45. /**
  46.  * nsITransport
  47.  *
  48.  * This interface provides a common way of accessing i/o streams connected
  49.  * to some resource.  This interface does not in any way specify the resource.
  50.  * It provides methods to open blocking or non-blocking, buffered or unbuffered
  51.  * streams to the resource.  The name "transport" is meant to connote the 
  52.  * inherent data transfer implied by this interface (i.e., data is being
  53.  * transfered in some fashion via the streams exposed by this interface).
  54.  *
  55.  * A transport can have an event sink associated with it.  The event sink 
  56.  * receives transport-specific events as the transfer is occuring.  For a
  57.  * socket transport, these events can include status about the connection.
  58.  * See nsISocketTransport for more info about socket transport specifics.
  59.  */
  60. [scriptable, uuid(cbb0baeb-5fcb-408b-a2be-9f8fc98d0af1)]
  61. interface nsITransport : nsISupports
  62. {
  63.     /**
  64.      * Open flags.
  65.      */
  66.     const unsigned long OPEN_BLOCKING   = 1<<0;
  67.     const unsigned long OPEN_UNBUFFERED = 1<<1;
  68.  
  69.     /**
  70.      * Open an input stream on this transport.
  71.      *
  72.      * Flags have the following meaning:
  73.      *
  74.      * OPEN_BLOCKING
  75.      *   If specified, then the resulting stream will have blocking stream
  76.      *   semantics.  This means that if the stream has no data and is not
  77.      *   closed, then reading from it will block the calling thread until
  78.      *   at least one byte is available or until the stream is closed.
  79.      *   If this flag is NOT specified, then the stream has non-blocking
  80.      *   stream semantics.  This means that if the stream has no data and is
  81.      *   not closed, then reading from it returns NS_BASE_STREAM_WOULD_BLOCK.
  82.      *   In addition, in non-blocking mode, the stream is guaranteed to 
  83.      *   support nsIAsyncInputStream.  This interface allows the consumer of
  84.      *   the stream to be notified when the stream can again be read.
  85.      *
  86.      * OPEN_UNBUFFERED
  87.      *   If specified, the resulting stream may not support ReadSegments.
  88.      *   ReadSegments is only gauranteed to be implemented when this flag is
  89.      *   NOT specified.
  90.      *
  91.      * @param aFlags
  92.      *        optional transport specific flags.
  93.      * @param aSegmentSize
  94.      *        if OPEN_UNBUFFERED is not set, then this parameter specifies the
  95.      *        size of each buffer segment (pass 0 to use default value).
  96.      * @param aSegmentCount
  97.      *        if OPEN_UNBUFFERED is not set, then this parameter specifies the
  98.      *        maximum number of buffer segments (pass 0 to use default value).
  99.      */
  100.     nsIInputStream openInputStream(in unsigned long aFlags,
  101.                                    in unsigned long aSegmentSize,
  102.                                    in unsigned long aSegmentCount);
  103.  
  104.     /**
  105.      * Open an output stream on this transport.
  106.      *
  107.      * Flags have the following meaning:
  108.      *
  109.      * OPEN_BLOCKING
  110.      *   If specified, then the resulting stream will have blocking stream
  111.      *   semantics.  This means that if the stream is full and is not closed,
  112.      *   then writing to it will block the calling thread until ALL of the
  113.      *   data can be written or until the stream is closed.  If this flag is
  114.      *   NOT specified, then the stream has non-blocking stream semantics.
  115.      *   This means that if the stream is full and is not closed, then writing
  116.      *   to it returns NS_BASE_STREAM_WOULD_BLOCK.  In addition, in non-
  117.      *   blocking mode, the stream is guaranteed to support
  118.      *   nsIAsyncOutputStream.  This interface allows the consumer of the
  119.      *   stream to be notified when the stream can again accept more data.
  120.      *
  121.      * OPEN_UNBUFFERED
  122.      *   If specified, the resulting stream may not support WriteSegments and
  123.      *   WriteFrom.  WriteSegments and WriteFrom are only gauranteed to be
  124.      *   implemented when this flag is NOT specified.
  125.      *
  126.      * @param aFlags
  127.      *        optional transport specific flags.
  128.      * @param aSegmentSize
  129.      *        if OPEN_UNBUFFERED is not set, then this parameter specifies the
  130.      *        size of each buffer segment (pass 0 to use default value).
  131.      * @param aSegmentCount
  132.      *        if OPEN_UNBUFFERED is not set, then this parameter specifies the
  133.      *        maximum number of buffer segments (pass 0 to use default value).
  134.      */
  135.     nsIOutputStream openOutputStream(in unsigned long aFlags,
  136.                                      in unsigned long aSegmentSize,
  137.                                      in unsigned long aSegmentCount);
  138.  
  139.     /**
  140.      * Close the transport and any open streams.
  141.      *
  142.      * @param aReason
  143.      *        the reason for closing the stream.
  144.      */
  145.     void close(in nsresult aReason);
  146.  
  147.     /**
  148.      * Set the transport event sink.
  149.      *
  150.      * @param aSink
  151.      *        receives transport layer notifications
  152.      * @param aEventTarget
  153.      *        indicates the event target to which the notifications should
  154.      *        be delivered.  if NULL, then the notifications may occur on
  155.      *        any thread.
  156.      */
  157.     void setEventSink(in nsITransportEventSink aSink,
  158.                       in nsIEventTarget aEventTarget); 
  159.     
  160.     /**
  161.      * Generic nsITransportEventSink status codes.  nsITransport
  162.      * implementations may override these status codes with their own more
  163.      * specific status codes (e.g., see nsISocketTransport).
  164.      */
  165.     const unsigned long STATUS_READING = 0x804b0008;
  166.     const unsigned long STATUS_WRITING = 0x804b0009;
  167. };
  168.  
  169. [scriptable, uuid(EDA4F520-67F7-484b-A691-8C3226A5B0A6)]
  170. interface nsITransportEventSink : nsISupports
  171. {
  172.     /**
  173.      * Transport status notification.
  174.      *
  175.      * @param aTransport
  176.      *        the transport sending this status notification.
  177.      * @param aStatus
  178.      *        the transport status (resolvable to a string using
  179.      *        nsIErrorService). See nsISocketTransport for socket specific
  180.      *        status codes and more comments.
  181.      * @param aProgress
  182.      *        the amount of data either read or written depending on the value
  183.      *        of the status code.  this value is relative to aProgressMax.
  184.      * @param aProgressMax
  185.      *        the maximum amount of data that will be read or written.  if
  186.      *        unknown, 0xFFFFFFFF will be passed.
  187.      */
  188.     void onTransportStatus(in nsITransport aTransport,
  189.                            in nsresult aStatus,
  190.                            in unsigned long long aProgress,
  191.                            in unsigned long long aProgressMax);
  192. };
  193.